CTab Class

A tab control is analogous to the dividers in a notebook or the labels in a file cabinet. By using a tab control, an application can define multiple pages for the same area of a window or dialog box. Each page consists of a certain type of information or a group of controls that the application displays when the user selects the corresponding tab.

See: About Tab Controls

Include file: CTab.inc.

Name	Description
AddTab	Retrieves the number of tabs and calls InsertTab to add a new tab.
AdjustRect	Calculates a tab control’s display area given a window rectangle, or calculates the window rectangle that would correspond to a specified display area.
DeleteAllItems	Removes all items from a tab control.
DeleteItem	Removes an item from a tab control.
DeselectAll	Resets items in a tab control, clearing any that were set to the TCIS_BUTTONPRESSED state.
GetCurFocus	Returns the index of the item that has the focus in a tab control.
GetCurSel	Determines the currently selected tab in a tab control.
GetExtendedStyle	Retrieves the extended styles that are currently in use for the tab control.
GetImageIndex	Gets the 0-based index in the tab control’s image list.
GetImageList	Retrieves the image list associated with a tab control.
GetItem	Retrieves information about a tab in a tab control.
GetItemCount	Retrieves the number of tabs in the tab control.
GetItemRect	Retrieves the bounding rectangle for a tab in a tab control.
GetRowCount	Retrieves the number of rows of tabs in the tab control.
GetText	Gets the name of a tab in a Tab control.
GetToolTips	Retrieves the handle to the ToolTip control associated with a tab control.
HighlightItem	Sets the highlight state of a tab item.
HitTest	Determines which tab, if any, is at a specified screen position.
InsertItem	Inserts a new tab in a tab control.
InsertTab	Inserts a new tab in a tab control.
RemoveImage	Removes an image from a tab control’s image list.
SetCurFocus	Sets the focus to a specified tab in a tab control.
SetCurSel	Selects a tab in a tab control.
SetExtendedStyle	Sets the extended styles that the tab control will use.
SetImageList	Assigns an image list to a tab control.
SetImageIndex	Sets the zero-based index in the tab control’s image list.
SetItem	Sets some or all of a tab’s attributes.
SetItemExtra	Sets the number of bytes per tab reserved for application-defined data in a tab control.
SetItemSize	Sets the width and height of tabs in a fixed-width or owner-drawn tab control.
SetMinTabWidth	Sets the width and height of tabs in a fixed-width or owner-drawn tab control.
SetPadding	Sets the amount of space (padding) around each tab’s icon and label in a tab control.
SetText	Sets the name of a tab in a Tab control.
SetToolTips	Assigns a ToolTip control to a tab control. You can use this macro or send the

AddTab

Adds a new tab in a tab control.

FUNCTION AddTab (BYVAL hTab AS HWND, BYVAL iImage AS LONG, BYVAL pwszText AS WSTRING PTR, _
   BYVAL lParam AS ..LPARAM = 0) AS LONG

Parameter	Description
hTab	Handle to the tab control.
iImage	Zero-based index of the image in the image list or -1 for no image.
pwszText	Pointer to a null-terminated string that contains the tab text when item information is being set.
lParam	Application-defined data associated with the tab control item.

Return value

Returns the index of the new tab if successful, or -1 otherwise.

AdjustRect

Calculates a tab control’s display area given a window rectangle, or calculates the window rectangle that would correspond to a specified display area.

SUB AdjustRect (BYVAL hTab AS HWND, BYVAL fLarger AS BOOLEAN, BYVAL prc AS RECT PTR)
SUB AdjustRect (BYVAL hTab AS HWND, BYVAL fLarger AS BOOLEAN, BYREF rc AS RECT)

Parameter	Description
hTab	Handle to the tab control.
fLarger	Operation to perform. If this parameter is TRUE, prc specifies a display rectangle and receives the corresponding window rectangle. If this parameter is FALSE, prc specifies a window rectangle and receives the corresponding display area.
prc	Pointer to a RECT structure that specifies the given rectangle and receives the calculated rectangle.
rc	A RECT structure that specifies the given rectangle and receives the calculated rectangle.

Remarks

This message applies only to tab controls that are at the top. It does not apply to tab controls that are on the sides or bottom.

Usage example

DIM rc AS RECT
CTab.AdjustRect(hTab, TRUE, @rc)
CTab.AdjustRect(hTab, FALSE, rc)

DeleteAllItems

Removes all items from a tab control.

FUNCTION DeleteAllItems (BYVAL hTab AS HWND) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Usage example

CTab.DeleteAllItems(hTab)

DeleteItem

Removes an item from a tab control.

FUNCTION DeleteItem (BYVAL hTab AS HWND, BYVAL iItem AS LONG) AS BOOLEAN

Parameter	Description
hTab	Handle to the tab control.
iItem	Zero-based index of the item to delete.

Return value

Returns TRUE if successful, or FALSE otherwise.

Usage example

CTab.DeleteItem(hTab, 2)

DeselectAll

Resets items in a tab control, clearing any that were set to the TCIS_BUTTONPRESSED state.

SUB DeselectAll (BYVAL hTab AS HWND, BYVAL fExcludeFocus AS BOOLEAN)

Parameter	Description
hTab	Handle to the tab control.
fExcludeFocus	Flag value that specifies the scope of the item deselection. If this parameter is set to FALSE, all tab items will be reset. If it is set to TRUE, all but the currently selected tab item will be reset.

Usage example

CTab.DeselectAll(hTab, TRUE)

GetCurFocus

Returns the index of the item that has the focus in a tab control.

FUNCTION GetCurFocus (BYVAL hTab AS HWND) AS LONG

Remarks

The item that has the focus may be different than the selected item.

Usage example

DIM curFocus AS LONG = CTab.GetCurFocus(hTab)

Remarks

The item that has the focus may be different than the selected item.

GetCurSel

Determines the currently selected tab in a tab control.

FUNCTION GetCurSel (BYVAL hTab AS HWND) AS LONG

Return value

Returns the index of the selected tab if successful, or -1 if no tab is selected.

Usage example

DIM curSel AS LONG = CTab.GetCurSel(hTab)

GetExtendedStyle

Retrieves the extended styles that are currently in use for the tab control.

FUNCTION GetExtendedStyle (BYVAL hTab AS HWND) AS DWORD

Return value

Returns a DWORD value that represents the extended styles currently in use for the tab control. This value is a combination of tab control extended styles.

Usage example

DIM style AS DWORD = CTab.GetExtendedStyle(hTab)

GetImageIndex

Gets the 0-based index of an image in the tab control’s image list.

FUNCTION GetImageIndex (BYVAL hTab AS HWND, BYVAL iItem AS DWORD) AS LONG

Parameter	Description
hTab	Handle to the tab control.
iItem	Zero-based index of the tab.

Return value

Returns the index of the image or -1 if not found.

Usage example

DIM idx AS LONG = CTab.GetImageIndex(hTab, 1)

GetImageList

Retrieves the image list associated with a tab control.

FUNCTION GetImageList (BYVAL hTab AS HWND) AS HIMAGELIST

Return value

Returns the handle to the image list if successful, or NULL otherwise.

Usage example

DIM hIml AS HIMAGELIST = CTab.GetImageList(hTab)

GetItem

Retrieves information about a tab in a tab control.

FUNCTION GetItem (BYVAL hTab AS HWND, BYVAL iItem AS DWORD, BYVAL ptcitem AS TCITEMW PTR) AS BOOLEAN
FUNCTION GetItem (BYVAL hTab AS HWND, BYVAL iItem AS DWORD, BYREF tcitem AS TCITEMW) AS BOOLEAN

Parameter	Description
hTab	Handle to the tab control.
iItem	Zero-based index of the tab.
ptcitem	Pointer to a TCITEM structure that specifies the information to retrieve and receives information about the tab. When the message is sent, the mask member specifies which attributes to return. If the mask member specifies the TCIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text, and the cchTextMax member must specify the size of the buffer.
tcitem	A TCITEM structure that specifies the information to retrieve and receives information about the tab. When the message is sent, the mask member specifies which attributes to return. If the mask member specifies the TCIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text, and the cchTextMax member must specify the size of the buffer.

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the TCIF_TEXT flag is set in the mask member of the TCITEM structure, the control may change the pszText member of the structure to point to the new text instead of filling the buffer with the requested text. The control may set the pszText member to NULL to indicate that no text is associated with the item.

Usage example

DIM item AS TCITEM
DIM2 bRes AS BOOLEAN = CTab.GetItem(hTab, @item)
DIM2 bRes AS BOOLEAN = CTab.GetItem(hTab, item)

GetItemCount

Retrieves the number of tabs in the tab control.

FUNCTION GetItemCount (BYVAL hTab AS HWND) AS LONG

Return value

Returns the number of items if successful, or zero otherwise.

Usage example

DIM count AS LONG = CTab.GetItemCount(hTab)

GetItemRect

Retrieves the bounding rectangle for a tab in a tab control.

FUNCTION GetItemRect (BYVAL hTab AS HWND, BYVAL iItem AS DWORD, BYVAL prc AS RECT PTR) AS BOOLEAN
FUNCTION GetItemRect (BYVAL hTab AS HWND, BYVAL iItem AS DWORD, BYREF rc AS RECT) AS BOOLEAN
FUNCTION GetItemRect (BYVAL hTab AS HWND, BYVAL iItem AS DWORD) AS RECT

Parameter	Description
hTab	Handle to the tab control.
iItem	Zero-based index of the tab.
prc	Pointer to a RECT structure that receives the bounding rectangle of the tab, in viewport coordinates.
rc	A RECT structure that receives the bounding rectangle of the tab, in viewport coordinates.

Return valu

Returns TRUE if successful, or FALSE otherwise.

Usage example

DIM rc AS RECT
CTab.GetItemRect(hTab, @rc)
CTab.GetItemRect(hTab, rc)
rc = GetItemRect(hTab)

GetRowCount

Retrieves the number of rows of tabs in the tab control.

FUNCTION GetRowCount (BYVAL hTab AS HWND) AS LONG

Return value

Returns the number of rows of tabs.

Remarks

Only tab controls that have the TCS_MULTILINE style can have multiple rows of tabs.

Usage example

DIM count AS LONG = CTab.GetRowCount(hTab)

GetText

Gets the name of a tab in a Tab control.

FUNCTION GetText (BYVAL hTab AS HWND, BYVAL nTabIndex AS DWORD, BYVAL pwszText AS WSTRING PTR, BYVAL cchTextMax AS LONG) AS BOOLEAN
FUNCTION GetText (BYVAL hTab AS HWND, BYVAL nTabIndex AS DWORD) AS DWSTRING

Parameter	Description
hTab	Handle to the tab control.
nTabIndex	Zero-based index of the tab.
pwszText	Pointer to a unicode string that will receive the name of the tab.
cchTextMax	Size in characters of the buffer pointed to by the pszText member.

DIM dwsText AS DWSTRING = CTab.GetText(hTab, 1)

GetToolTips

Retrieves the handle to the tooltip control associated with a tab control.

FUNCTION GetToolTips (BYVAL hTab AS HWND) AS HWND

Return value

Returns the handle to the tooltip control if successful, or NULL otherwise.

Usage example

DIM hTooltips AS HWND = CTab.GetToolTips(hTab)

HighlightItem

Sets the highlight state of a tab item.

FUNCTION HighlightItem (BYVAL hTab AS HWND, BYVAL idItem AS LONG, BYVAL fHighlight AS WORD) AS LONG

Parameter	Description
hTab	Handle to the tab control.
idItem	Zero-based index of the tab.
fHighlight	Value specifying the highlight state to be set. If this value is nonzero, the tab is highlighted. If this value is zero, the tab is set to its default state.

Return value

Returns nonzero if successful, or zero otherwise.

Remarks

In Comctl32.dll version 6.0, this macro has no visible effect when a theme is active.

Usage example

CTab.HighlightItem(hTab, 1, 1)

HitTest

Determines which tab, if any, is at a specified screen position.

FUNCTION HitTest (BYVAL hTab AS HWND, BYREF pInfo AS TC_HITTESTINFO PTR) AS LONG
FUNCTION HitTest (BYVAL hTab AS HWND, BYREF info AS TC_HITTESTINFO) AS LONG

Parameter	Description
hTab	Handle to the tab control.
pInfo	Pointer to a TCHITTESTINFO structure that specifies the screen position to test.
info	A TCHITTESTINFO structure that specifies the screen position to test.

Return value

Returns the index of the tab, or -1 if no tab is at the specified position.

InsertItem

Inserts a new tab in a tab control.

FUNCTION InsertItem (BYVAL hTab AS HWND, BYVAL iItem AS DWORD, BYVAL pItem AS TCITEMW PTR) AS LONG
FUNCTION InsertItem (BYVAL hTab AS HWND, BYVAL iItem AS DWORD, BYREF item AS TCITEMW) AS LONG

Parameter	Description
hTab	Handle to the tab control.
iItem	Zero-based index of the new tab.
pItem	Pointer to a TCITEMW structure that specifies the attributes of the tab. The dwState and dwStateMask members of this structure are ignored by this message.
item	A TCITEMW structure that specifies the attributes of the tab. The dwState and dwStateMask members of this structure are ignored by this message.

Return value

Returns the index of the new tab if successful, or -1 otherwise.

InsertTab

Inserts a new tab in a tab control.

FUNCTION InsertTab (BYVAL hTab AS HWND, BYVAL nTabIndex AS DWORD, BYVAL iImage AS LONG, _
   BYVAL pwszText AS WSTRING PTR, BYVAL lParam AS ..LPARAM = 0) AS LONG

Parameter	Description
hTab	Handle to the tab control.
nTabInxex	Zero-based index of the tab.
iImage	Zero-based index of the image in the image list or -1 for no image.
pwszText	Pointer to a null-terminated string that contains the tab text when item information is being set.
lParam	Application-defined data associated with the tab control item.

Return value

Returns the index of the new tab if successful, or -1 otherwise.

RemoveImage

Removes an image from a tab control’s image list.

SUB RemoveImage (BYVAL hTab AS HWND, BYVAL iImage AS LONG)

Parameter	Description
hTab	Handle to the tab control.
iImage	Zero-based index of the image to remove.

Remarks

The tab control updates each tab’s image index, so each tab remains associated with the same image as before. If a tab is using the image being removed, the tab will be set to have no image.

Usage example

CTab.RemoveImage(hTab, 2)

SetCurFocus

Sets the focus to a specified tab in a tab control.

SUB SetCurFocus (BYVAL hTab AS HWND, BYVAL iItem AS LONG)

Parameter	Description
hTab	Handle to the tab control.
iItem	Zero-based index of the tab that gets the focus.

Remarks

If the tab control has the TCS_BUTTONS style (button mode), the tab with the focus may be different from the selected tab. For example, when a tab is selected, the user can press the arrow keys to set the focus to a different tab without changing the selected tab. In button mode, SetCurFocus sets the input focus to the button associated with the specified tab, but it does not change the selected tab.

If the tab control does not have the TCS_BUTTONS style, changing the focus also changes the selected tab. In this case, the tab control sends the TCN_SELCHANGING and TCN_SELCHANGE notification codes to its parent window.

Usage example

CTab.SetCurFocus(hTab, 2)

SetCurSel

Selects a tab in a tab control.

FUNCTION SetCurSel (BYVAL hTab AS HWND, BYVAL iItem AS LONG) AS LONG

Parameter	Description
hTab	Handle to the tab control.
iItem	Zero-based index of the tab to select.

Return value

Returns the index of the previously selected tab if successful, or -1 otherwise.

Remarks

A tab control does not send a TCN_SELCHANGING or TCN_SELCHANGE notification code when a tab is selected using the TCM_SETCURSEL message.

Usage example

CTab.SetCurSel(hTab, 2)

SetExtendedStyle

Sets the extended styles that the tab control will use.

FUNCTION SetExtendedStyle (BYVAL hTab AS HWND, BYVAL dwExStyle AS DWORD) AS DWORD

Parameter	Description
hTab	Handle to the tab control.
dwExStyle	Value that contains the new tab control extended styles.

Return value

Returns a DWORD value that contains the previous tab control extended styles.

Usage example

CTab.SetExtendedStyle(hTab, exStyle)

SetImageList

Assigns an image list to a tab control.

FUNCTION SetImageList (BYVAL hTab AS HWND, BYVAL himl AS HIMAGELIST) AS BOOLEAN

Parameter	Description
hTab	Handle to the tab control.
himl	Handle to the image list to assign to the tab control.

Return value

Returns the handle to the previous image list, or NULL if there is no previous image list.

Usage example

DIM hOldImlList AS HIMAGELIST = CTab.SetExtendedStyle(hTab, hIml)

SetImageIndex

Sets the zero-based index in the tab control’s image list.

FUNCTION SetImageIndex (BYVAL hTab AS HWND, BYVAL iItem AS LONG, BYVAL iImage AS LONG) AS BOOLEAN

Parameter	Description
hTab	Handle to the tab control.
iImage	Zero-based index of the tab control’s image list.

Return value

Returns TRUE if successful, or FALSE otherwise.

Usage example

CTab.SetImageIndex(hTab, 2)

SetItem

Sets some or all of a tab’s attributes.

FUNCTION SetItem (BYVAL hTab AS HWND, BYVAL iItem AS LONG, BYREF pitem AS TCITEMW PTR) AS LONG
FUNCTION SetItem (BYVAL hTab AS HWND, BYVAL iItem AS LONG, BYREF item AS TCITEMW) AS LONG

Parameter	Description
hTab	Handle to the tab control.
iItem	Zero-based index of the item.
pitem	Pointer to a TCITEMW structure that contains the new item attributes. The mask member specifies which attributes to set. If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.
item	A TCITEMW structure that contains the new item attributes. The mask member specifies which attributes to set. If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return value

Returns TRUE if successful, or FALSE otherwise.

SetItemExtra

Sets the number of bytes per tab reserved for application-defined data in a tab control.

FUNCTION SetItemExtra (BYVAL hTab AS HWND, BYVAL cb AS LONG) AS BOOLEAN

Parameter	Description
hTab	Handle to the tab control.
cb	Number of extra bytes.

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

By default, the number of extra bytes is four. An application that changes the number of extra bytes cannot use the TCITEMW structure to retrieve and set the application-defined data for a tab. Instead, you must define a new structure that consists of the TCITEMHEADER structure followed by application-defined members.

An application should only change the number of extra bytes when a tab control does not contain any tabs.

SetItemSize

Sets the width and height of tabs in a fixed-width or owner-drawn tab control.

FUNCTION SetItemSize (BYVAL hTab AS HWND, BYVAL x AS LONG, BYVAL y AS LONG) AS DWORD

Parameter	Description
hTab	Handle to the tab control.
x	New width, in pixels.
y	New height, in pixels.

Return value

Returns the old width and height. The width is in the LOWORD of the return value, and the height is in the HIWORD.

Usage example

CTab.SetItemSize(hTab, 50, 30)

SetMinTabWidth

Sets the width and height of tabs in a fixed-width or owner-drawn tab control.

FUNCTION SetMinTabWidth (BYVAL hTab AS HWND, BYVAL cx AS LONG) AS LONG

Parameter	Description
hTab	Handle to the tab control.
cx	Minimum width to be set for a tab control item. If this parameter is set to -1, the control will use the default tab width.

Return value

Returns a value that represents the previous minimum tab width.

Usage example

CTab.SetMinTabWidth(hTab, 50)

SetPadding

Sets the amount of space (padding) around each tab’s icon and label in a tab control.

SUB SetPadding (BYVAL hTab AS HWND, BYVAL cx AS INTEGER, BYVAL cy AS INTEGER)

Parameter	Description
hTab	Handle to the tab control.
cx	Amount of horizontal padding, in pixels.
cy	Amount of vertical padding, in pixels.

Usage example

CTab.SetPadding(hTab, 10, 10)

SetText

Sets the name of a tab in a Tab control.

FUNCTION SetText (BYVAL hTab AS HWND, BYVAL nTabIndex AS DWORD, BYVAL pwszText AS WSTRING PTR) AS BOOLEAN

Parameter	Description
hTab	Handle to the tab control.
nTabIndex	Zero-based index of the tab.
pwszText	Pointer to a unicode string with the name of the tab.

Usage example

CTab.SetText(hTab, 2, "New text")

SetToolTips

Assigns a ToolTip control to a tab control.

SUB SetToolTips (BYVAL hTab AS HWND, BYVAL hwndTT AS HWND)

Parameter	Description
hTab	Handle to the tab control.
hwndTT	Handle to the tooltip control.

Usage example

CTab.SetToolTips(hTab, hwndTT)